<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: C++ Support</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__libraries__c_p_l_u_s_p_l_u_s-_s_u_p_p_o_r_t.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">C++ Support </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Android platform provides a very minimal C++ runtime support library (/system/lib/libstdc++) and corresponding headers for it in the NDK.</p>
<p>By default, this 'system' runtime does <em>not</em> provide the following:</p>
<ul>
<li>Standard C++ Library support (except a few trivial headers).</li>
<li>C++ exceptions support</li>
<li>RTTI support</li>
</ul>
<p>However, the NDK provides various "helper C++ runtimes" which can provide them, or a subset of these features.</p>
<p>To select the runtime you want to use, define APP_STL inside your Application.mk to one of the following values: </p>
<pre class="fragment">    system          -&gt; Use the default minimal system C++ runtime library.
    gabi++_static   -&gt; Use the GAbi++ runtime as a static library.
    gabi++_shared   -&gt; Use the GAbi++ runtime as a shared library.
    stlport_static  -&gt; Use the STLport runtime as a static library.
    stlport_shared  -&gt; Use the STLport runtime as a shared library.
    gnustl_static   -&gt; Use the GNU STL as a static library.
    gnustl_shared   -&gt; Use the GNU STL as a shared library.
    c++_static      -&gt; Use the LLVM libc++ as a static library.
    c++_shared      -&gt; Use the LLVM libc++ as a shared library.
</pre><p>The 'system' runtime is the default if there is no APP_STL definition in your Application.mk. As an example, to use the static GNU STL, add a line like: </p>
<pre class="fragment">    APP_STL := gnustl_static
</pre><p>To your Application.mk. You can only select a single C++ runtime that all your code will depend on. It is not possible to mix shared libraries compiled against different C++ runtimes.</p>
<p>IMPORTANT: Defining APP_STL in Android.mk has no effect!</p>
<p>If you are not using the NDK build system, you can still use STLport, libc++ or GNU STL via "make-standalone-toolchain.sh --stl=". see <a href="md_3__key__topics__building__s_t_a_n_d_a_l_o_n_e-_t_o_o_l_c_h_a_i_n.html">Standalone Toolchain</a> for more details.</p>
<p>The capabilities of the various runtimes vary. See this table: </p>
<pre class="fragment">                C++       C++   Standard
              Exceptions  RTTI    Library

    system        no       no        no
    gabi++       yes      yes        no
    stlport      yes      yes       yes
    gnustl       yes      yes       yes
    libc++       yes      yes       yes
</pre><p>#</p>
<h2>Runtimes</h2>
<h3>System runtime</h3>
<p>The system runtime only provides a very small number of C++ standard headers.</p>
<p>This corresponds to the actual C++ runtime provided by the Android platform. If you use it, your C++ binaries will automatically be linked against the system libstdc++.</p>
<p>The only headers provided here are the following: </p>
<pre class="fragment">    cassert cctype cerrno cfloat climits cmath csetjmp csignal cstddef
    cstdint cstdio cstdlib cstring ctime cwchar new stl_pair.h typeinfo
    utility
</pre><p>Anything else is <em>not</em> supported, including std::string or std::vector.</p>
<h3>GAbi++ runtime</h3>
<p>This is a new minimalistic runtime that provides the same headers than the system one, with the addition of RTTI (RunTime Type Information) and exception handling support.</p>
<p>If you insist on using it, read the "RTTI Support" and "Static runtime considerations" sections below.</p>
<h3>STLport runtime</h3>
<p>This is a port of STLport (<a href="http://www.stlport.org">http://www.stlport.org</a>) that can be used on Android. It will provide you with a complete set of C++ standard library headers, with RTTI and exception handling support.</p>
<p>That's because the library embeds its own copy of GAbi++.</p>
<p>Available as both both static and shared libraries. To use it, use either one of these two lines in your Application.mk: </p>
<pre class="fragment">  APP_STL := stlport_shared
  APP_STL := stlport_static
</pre><p>Note that 'stlport_shared' is preferred, for reasons explained in "Static runtime considerations". The shared library file is named libstlport_shared.so instead of "libstdc++.so" as on other platforms.</p>
<h3>GNU STL runtime</h3>
<p>This is the GNU Standard C++ Library (a.k.a. libstdc++-v3), providing the more features. Note that the shared library file is named "libgnustl_shared.so".</p>
<p>If you want to use it, please read the "C++ Exceptions support", "RTTI Support" and "Static runtime considerations" sections below.</p>
<h3>libC++ runtime:</h3>
<p>This is a port of LLVM libc++: <a href="http://libcxx.llvm.org/">http://libcxx.llvm.org/</a>. Note that the shared library file is named "libc++_shared.so".</p>
<p>Please read the "C++ Exceptions support", "RTTI Support" and "Static runtime considerations" sections below.</p>
<h2>II. Important Considerations</h2>
<h3>C++ Exceptions support</h3>
<p>The NDK toolchain supports C++ exceptions, since NDK r5, however all C++ sources are compiled with -fno-exceptions support by default, for compatibility reasons with previous releases.</p>
<p>To enable it, use the new LOCAL_CPP_FEATURES variable in your Android.mk, as in: </p>
<pre class="fragment">    LOCAL_CPP_FEATURES += exceptions
</pre><p>See docs/ANDROID-MK.html for more details about this variable.</p>
<p>Another way to do the same is to define it in your LOCAL_CPPFLAGS definition (but using LOCAL_CPP_FEATURES is preferred), as in: </p>
<pre class="fragment">    LOCAL_CPPFLAGS += -fexceptions
</pre><p>More simply, add a single line to your Application.mk, the setting will automatically apply to all your project's NDK modules: </p>
<pre class="fragment">    APP_CPPFLAGS += -fexceptions
</pre><p>IMPORTANT: You <em>will</em> have to select a C++ runtime that supports exceptions to be able to link / run your code.</p>
<h3>RTTI support</h3>
<p>Similarly, the NDK toolchain supports C++ RTTI (RunTime Type Information) since NDK r5, but all C++ sources are built with -fno-rtti by default for compatibility reasons. To enable it, add the following to your module declarations: </p>
<pre class="fragment">    LOCAL_CPP_FEATURES += rtti
</pre><p>This will be equivalent to: </p>
<pre class="fragment">    LOCAL_CPPFLAGS += -frtti
</pre><p>Or more simply to your Application.mk: </p>
<pre class="fragment">    APP_CPPFLAGS += -frtti
</pre><h3>Static runtimes</h3>
<p>Please keep in mind that the static library variant of a given C++ runtime SHALL ONLY BE LINKED INTO A SINGLE BINARY for optimal conditions.</p>
<p>What this means is that if your project consists of a single shared library, you can link against, e.g., stlport_static, and everything will work correctly.</p>
<p>On the other hand, if you have two shared libraries in your project (e.g. libfoo.so and libbar.so) which both link against the same static runtime, each one of them will include a copy of the runtime's code in its final binary image. This is problematic because certain global variables used/provided internally by the runtime are duplicated.</p>
<p>This is likely to result in code that doesn't work correctly, for example:</p>
<ul>
<li>memory allocated in one library, and freed in the other would leak or even corrupt the heap.</li>
<li>exceptions raised in libfoo.so cannot be caught in libbar.so (and may simply crash the program).</li>
<li>the buffering of std::cout not working properly</li>
</ul>
<p>This problem also happens if you want to link an executable and a shared library to the same static library.</p>
<p>In other words, if your project requires several shared library modules, then use the shared library variant of your C++ runtime.</p>
<h3>Shared runtimes</h3>
<p>Due to an issue which is fixed in JB-MR2 API level 18 (issue
<a href="https://code.google.com/p/android/issues/detail?id=41790">41790</a> and <a href="https://code.google.com/p/android/issues/detail?id=34416">34416</a>
), if you use the shared library variant of a given C++ runtime, keep in mind that you must load it before any library that depends on it when your application starts.</p>
<p>As an example, let's consider the case where we have the following modules</p>
<ul>
<li>libfoo.so</li>
<li>libbar.so which is used by libfoo.so</li>
<li>libstlport_shared.so, used by both libfoo and libbar</li>
</ul>
<p>You will need to load the libraries in reverse dependency order, as in: </p>
<pre class="fragment">    static {
      System.loadLibrary("stlport_shared");
      System.loadLibrary("bar");
      System.loadLibrary("foo");
    }
</pre><p>Note that you shouldn't use the 'lib' prefix when calling System.loadLibrary(), unless you specify the full path as in: </p>
<pre class="fragment">System.loadLibrary("/path/to/libstlport_shared.so")
</pre><p>Which is not recommended, since this hard-codes the path in your code.</p>
<h2>III. EXTRAS</h2>
<h3>STLport-specific issues</h3>
<p>This NDK provides prebuilt static and shared libraries for STLport, but you can force it to be rebuilt from sources by defining the following in your environment or your Application.mk before building: </p>
<pre class="fragment">    STLPORT_FORCE_REBUILD := true
</pre><p>STLport is licensed under a BSD-style open-source license. See sources/cxx-stl/stlport/README for more details about the library.</p>
<h3>GNU libstdc++ license is GPLv3 + linking exception</h3>
<p>Be aware that the GNU libstdc++ is covered by the GPLv3 license (and <em>not</em> the LGPLv2 or LGPLv3 as some assume), full details available here: </p>
<pre class="fragment">    http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html
</pre><p>Be sure that you comply with all clauses of this license.</p>
<h3>libc++-specific issues:</h3>
<p>"-std=c++11" is turned on by default.</p>
<p>Similiar to GNU libstdc++, you need to explicitly turns on exceptions or rtti support in "LOCAL_CPP_FEATURES" if you wish.</p>
<p>It's likely that you need libatomic if you #include &lt;atomic&gt;. Add "LOCAL_LDLIBS += -latomic" for ndk-build, and "-latomic" for standalone toolchain. Note that -latomic is only available in gcc4.8, not gcc4.6 (deprecated and removed since r10e). Clang3.4/3.3 use gcc4.8's as/ld/headers/libraries so they get -latomic too. The version of libatomic in gcc4.8 <em>may</em> work for gcc4.6, although it's not tested and you have to copy them manually.</p>
<p>This NDK provides prebuilt static and shared libraries for libc++ compiled by clang3.4, but you can force it to be rebuilt from sources by defining the following in your environment or your Application.mk before building: </p>
<pre class="fragment">    LIBCXX_FORCE_REBUILD := true
</pre><p>Around 99% of current 4640 tests passes when compiling libc++ with clang3.4 for all supported ABIs. The remaining fails are mostly in the areas of wchar_t and locale Android bionic don't support. Switching locale from the default produces the following warning in logcat </p>
<pre class="fragment">    newlocale() WARNING: Trying to set locale to en_US.UTF-8 other than "", "C" or "POSIX"
</pre><p>Initial support at r9d uses gabi++ as run-time also causes some issues in the nested exception and propagation too. Almost all are fixed after switching to libc++abi.</p>
<p>Header include/atomic is fixed for gcc which doesn't support <em>Atomic in c++ mode. A dozen more fails when compiling libc++ with gcc4.8/gcc4.9 mostly in is_trivially</em>* tests.</p>
<p>Using libc++ with gcc4.6 is not recommended (at least not tested at this moment) because its c++11 support isn't great</p>
<p>See "black_list*" in tests/device/test-libc++-shared-full/jni/Android.mk for tests which fail to compile, and tests/device/test-libc++-shared-full/BROKEN_RUN for tests which fails to run correctly.</p>
<h3>Future Plans:</h3>
<ul>
<li>uSTL support? </li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
